| API Documentation |  |

- MAIN PAGE
- NAMESPACES
- CLASSES

Public Member Functions | Static Public Member Functions | List of all members
nkGraphics::Program Class Referenceabstract

Holds all informations related to GPU programs, and manages their compilation. More...

Inheritance diagram for nkGraphics::Program:

## Public Member Functions
| Program (System *system) noexcept
virtual | ~Program ()
const ProgramCompilationResult & | getLastCompilationResult () const
bool | isFromFile () const
bool | isFromMemory () const
const ProgramSourcesHolder & | getMemory () const
nkMemory::BufferView< const ProgramSemanticEntry > | getInputSemantics () const
unsigned int | getId () const
PROGRAM_TYPE | getType () const
PROGRAM_COMPILATION_PROFILE | getProfile () const
virtual void | setFromMemory (const ProgramSourcesHolder &memory)
virtual void | setDefines (const ProgramSourcesHolder &memory)
void | setFromFiles (nkMemory::StringView folder)
void | setFileExtensions (nkMemory::StringView value)
void | setId (unsigned int id)
void | setProfile (PROGRAM_COMPILATION_PROFILE profile)
void | setActivateCrossCompilerDefines (bool value)
bool | prepareMemoryWithFiles ()
virtual bool | loadFromMemory ()=0
virtual bool | tryToLoadFrom (ProgramSourcesHolder &newMemory)=0
virtual bool | load () override
virtual void | unload () override
virtual void | exportClassToTree (nkExport::Node *rootNode) override
virtual void | importClassFromTree (nkExport::Node *rootNode) override
Public Member Functions inherited from nkGraphics::Resource
virtual | ~Resource ()
bool | isReadyForRendering () const
bool | isUnloaded () const
RESOURCE_LOAD_STATE | getLoadState () const
nkMemory::StringView | getPath () const
RESOURCE_TYPE | getTypeName () const
nkMemory::StringView | getName () const
System * | getSystem () const
bool | getHidden () const
bool | getGpuUploadCanBeDeferred () const
virtual void | setPath (nkMemory::StringView value)
void | setName (nkMemory::StringView value)
void | setHidden (bool value)
void | setGpuUploadCanBeDeferred (bool value)
Public Member Functions inherited from nkExport::Exportable
| Exportable () noexcept
virtual | ~Exportable ()

## Static Public Member Functions
static nkMemory::UniquePtr< Program > | create (System *system=nullptr)

## Detailed Description

Holds all informations related to GPU programs, and manages their compilation.

See ProgramManager::createOrRetrieve() or Program::create() for instantiation.

## Constructor & Destructor Documentation

## ◆ Program()

nkGraphics::Program::Program | ( | System * | system | ) |
| noexcept

Constructor.

Parameters

  system | The system the resource should live in.

Remarks
  For creation, see ProgramManager::createOrRetrieve(), or Program::create().

## ◆ ~Program()

virtual nkGraphics::Program::~Program | ( |  | ) |
| virtual

Destructor.

## Member Function Documentation

## ◆ getLastCompilationResult()

const ProgramCompilationResult& nkGraphics::Program::getLastCompilationResult | ( |  | ) | const

Returns
  The last compilation result. Generated whenever a loading is called.

## ◆ isFromFile()

bool nkGraphics::Program::isFromFile | ( |  | ) | const

Returns
  Whether the program has been made from files (true) or not (false).

## ◆ isFromMemory()

bool nkGraphics::Program::isFromMemory | ( |  | ) | const

Returns
  Whether the program has been made from an internal memory (true) or not (false).

## ◆ getMemory()

const ProgramSourcesHolder& nkGraphics::Program::getMemory | ( |  | ) | const

Returns
  The currently used sources memory.

## ◆ getInputSemantics()

nkMemory::BufferView<const ProgramSemanticEntry> nkGraphics::Program::getInputSemantics | ( |  | ) | const

Returns
  The semantics of the program.

## ◆ getId()

unsigned int nkGraphics::Program::getId | ( |  | ) | const

Returns
  The id of the program.

## ◆ getType()

PROGRAM_TYPE nkGraphics::Program::getType | ( |  | ) | const

Returns
  The type of program. Detected, depending on what kind of memory is loaded.

## ◆ getProfile()

PROGRAM_COMPILATION_PROFILE nkGraphics::Program::getProfile | ( |  | ) | const

Returns
  The profile used by the program.

## ◆ setFromMemory()

virtual void nkGraphics::Program::setFromMemory | ( | const ProgramSourcesHolder & | memory | ) |
| virtual

Sets the program from an already loaded memory set.

The memory used will need to fit some constraints for a Program to find back relevant data :

- The function to execute in a program needs to be named "main", for all stages except raytracing.
- For raytracing stage, depending on their role, entry functions should be named : "miss", "raygen", "closestHit".

Parameters

  memory | The memory to use.

## ◆ setDefines()

virtual void nkGraphics::Program::setDefines | ( | const ProgramSourcesHolder & | memory | ) |
| virtual

Sets the defines to use within the program. Can be useful to add defines and then load a program from a folder.

Parameters

  memory | The memory to copy de defines from.

## ◆ setFromFiles()

void nkGraphics::Program::setFromFiles | ( | nkMemory::StringView | folder | ) |

Sets the folder from which the program should load its sources. The files that can be loaded are :

- vertexShader.x -> vertex stage
- hullShader.x -> hull stage
- domainShader.x -> domain stage
- geometryShader.x -> geometry stage
- pixelShader.x -> pixel stage
- computeShader.x -> compute stage
- raytracingShader.x -> raytracing stage

With x being the extension set through the setFileExtensions() function, or the default which depends on the type of renderer :

- RENDERING_API::D3D11, RENDERING_API::D3D12 -> .hlsl files
- RENDERING_API::GLES -> .glsl files

Parameters

  folder | The path of the folder to load from, relative to the working directory. See nkResources::ResourceManager for the path naming conventions.

## ◆ setFileExtensions()

void nkGraphics::Program::setFileExtensions | ( | nkMemory::StringView | value | ) |

Sets the extension to search for when parsing the given folder. This allows to override the default behavior of the file seeking algorithm, enabling to put in common files loaded for all type of renderers, for instance.

Parameters

  value | The extension to append to the file names.

## ◆ setId()

void nkGraphics::Program::setId | ( | unsigned int | id | ) |

Sets the id of the program.

Parameters

  id | The id to use.

## ◆ setProfile()

void nkGraphics::Program::setProfile | ( | PROGRAM_COMPILATION_PROFILE | profile | ) |

Sets the profile to use for the sources compilation. Some notes regarding the various renderers :

- The Dx11 renderer cannot use a shader model higher than 5.0, which is the default it will use.
- The Dx12 renderer uses the new DirectX Compiler and as such, can't go lower than 6.0. By default, it will adapt to the GPU it works on by querying and using the highest profile supported. Setting a profile manually will force it into a stable shader model for a given program, causing it to :
  - Use a lower shader model than the max supported if the version provided is lower.
  - Issue a warning that the version set is higher than the max supported, and attempt a compilation anyway with the highest profile supported.
  This should ensure future versions won't be an issue to already written programs, and that lower profile support won't fully lock compilation if not all features are used.

Parameters

  profile | The profile to use during compilation.

Remarks
  These profiles are currently only relevant for DirectX based renderers. This means the Gles renderer will ignore the profiles provided and automatically specify #version 330 in the source file. Client GLSL code does not need to specify this line as a result.

## ◆ setActivateCrossCompilerDefines()

void nkGraphics::Program::setActivateCrossCompilerDefines | ( | bool | value | ) |

Activates or not the cross compiler defines feeding. This is a good tool to use if you plan on making your programs work both on DirectX and OpenGL based renderers. Setting this to true will enable keywords within hlsl / glsl sources to ease cross-platform development. By default, this flag is off to lower processing times while loading programs.
If set to on, new keywords will become available to program sources, that will translate correctly into both languages :

Nk keyword | Hlsl translation | Glsl translation |
--- | --- | --- | ---
Types
nkBool2 | bool2 | bvec2
nkBool3 | bool3 | bvec3
nkBool4 | bool4 | bvec4
nkFloat2 | float2 | vec2
nkFloat3 | float3 | vec3
nkFloat4 | float4 | vec4
nkInt2 | int2 | ivec2
nkInt3 | int3 | ivec3
nkInt4 | int4 | ivec4
nkUint2 | uint2 | uvec2
nkUint3 | uint3 | uvec3
nkUint4 | uint4 | uvec4
nkFloat2x2 | float2x2 | mat2
nkFloat3x3 | float3x3 | mat3
nkFloat4x4 | float4x4 | mat4
nkFloat2x4 | float2x4 | mat2x4
nkTexture2d | Texture2D | sampler2D
nkTexture2dArray | Texture2DArray | sampler2DArray
nkTexture2dShadow | Texture2D | sampler2DShadow
nkTexture3d | Texture3D | sampler3D
nkTextureCube | TextureCube | samplerCube
nkSampler | SamplerState | bool (no valid translation)
nkSamplerComparison | SamplerComparisonState | bool (no valid translation)
Textures declarations
nkTexture2dDecl(name, slot) | Texture2D [name] : register(t[slot]) | layout(binding = [slot]) uniform sampler2D [name]
nkTexture2dArrayDecl(name, slot) | Texture2DArray [name] : register(t[slot]) | layout(binding = [slot]) uniform sampler2DArray [name]
nkTexture2dShadowDecl(name, slot) | Texture2D [name] : register(t[slot]) | layout(binding = [slot]) uniform sampler2DShadow [name]
nkTexture3dDecl(name, slot) | Texture3D [name] : register(t[slot]) | layout(binding = [slot]) uniform sampler3D [name]
nkTextureCubeDecl(name, slot) | TextureCube [name] : register(t[slot]) | layout(binding = [slot]) uniform samplerCube [name]
nkSamplerDecl(name, slot) | SamplerState [name] : register(s[slot]) | bool [name] (no valid translation)
nkSamplerComparisonDecl(name, slot) | SamplerComparisonState [name] : register(s[slot]) | bool [name] (no valid translation)
Textures functions
nkSample(tex, sampler, uvs) | [tex].Sample([sampler], [uvs]) | texture([tex], [uvs])
nkSampleBias(tex, sampler, uvs, bias) | [tex].SampleBias([sampler], [uvs], [bias]) | texture([tex], [uvs], [bias])
nkSampleLevel(tex, sampler, uvs, level) | [tex].SampleLevel([sampler], [uvs], [level]) | textureLod([tex], [uvs], [level])
nkSampleCompare(tex, sampler, uvs, value) | [tex].SampleCmp([sampler], [uvs], [value]) | texture([tex], vec3([uvs], [level]))
nkSampleCompareLevelZero(tex, sampler, uvs, value) | [tex].SampleCmpLevelZero([sampler], [uvs], [value]) | textureLod([tex], vec3([uvs], 0), [level])
nkLoad(tex, texel) | [tex].Load([texel]) | texelFetch([tex], [texel.xy], [texel.z])
nkLoadOffset(tex, texel, offset) | [tex].Load([texel], [offset]) | texelFetchOffset([tex], [texel.xy], [texel.z], [offset])
Constant declarations
nkConstantBufferDecl(name, slot) | cbuffer [name] : register(b[slot]) | layout(binding = [slot], std140) uniform [name]
Comparison functions
nkLessThan(a, b) | ([a] < [b]) | lessThan([a], [b])
General functions
nkMul(a, b) | mul([a], [b]) | ([a] * [b])
nkAtan2(a, b) | atan2([a], [b]) | atan([a], [b])
nkFrac(a) | frac([a]) | fract([a])
nkSaturate(a) | saturate([a]) | clamp([a], 0, 1)
nkDdx(a) | ddx([a]) | dFdx([a])
nkDdy(a) | ddy([a]) | dFdy([a])
nkLerp(a, b, c) | lerp([a], [b], [c]) | mix([a], [b], [c])

Parameters

  value | Whether the defines should be set (true) or not (false).

## ◆ prepareMemoryWithFiles()

bool nkGraphics::Program::prepareMemoryWithFiles | ( |  | ) |

If the program is defined from a folder, prepares the memory with the source files content.

Returns
  If the loading went well (true) or not (false).

## ◆ loadFromMemory()

virtual bool nkGraphics::Program::loadFromMemory | ( |  | ) |
| pure virtual

Loads the program, from the memory currently set.

Returns
  If the loading went well (true) or not (false).

## ◆ tryToLoadFrom()

virtual bool nkGraphics::Program::tryToLoadFrom | ( | ProgramSourcesHolder & | newMemory | ) |
| pure virtual

Tries to load from a provided memory, and swap the current state with the newly submitted state only on success. If it fails, the program state is not changed.

Parameters

  newMemory | The memory to try to load from.

Returns
  If the loading went well (true) or not (false).

## ◆ load()

virtual bool nkGraphics::Program::load | ( |  | ) |
| override virtual

Loads and compiles the program.
When processing the compilation, a program will automatically add some defines to help with cross renderer development :

- NK_HLSL : in case of a DirectX based renderer
- NK_GLSL : in case of an OpenGL based renderer

Allowing to write code that will differentiate between both compilers :

    #if defined(NK_HLSL)
        float4 main (in float4 pos : SV_POSITION) : SV_TARGET
        {
            return 1 ;
        }
    #elif defined(NK_GLSL)
        out vec4 color ;
        void main ()
        {
            color = vec4(1) ;
        }
    #endif

Returns
  If the loading went well (true) or not (false).

Implements nkGraphics::Resource.

## ◆ unload()

virtual void nkGraphics::Program::unload | ( |  | ) |
| override virtual

Unloads and frees the internal resources of the program.

Implements nkGraphics::Resource.

## ◆ exportClassToTree()

virtual void nkGraphics::Program::exportClassToTree | ( | nkExport::Node * | rootNode | ) |
| override virtual

Exports an item into a tree describing its structure and its data.

Parameters

  rootNode | The node into which the object has to write its related information.

Implements nkExport::Exportable.

## ◆ importClassFromTree()

virtual void nkGraphics::Program::importClassFromTree | ( | nkExport::Node * | rootNode | ) |
| override virtual

Imports information from a tree which is supposed to describe its structure and data.

Parameters

  rootNode | The root node of the tree holding the information.

Implements nkExport::Exportable.

## ◆ create()

static nkMemory::UniquePtr<Program> nkGraphics::Program::create | ( | System * | system = `nullptr` | ) |
| static

Creates a standalone resource, linking it to a system, but no manager. This method can be used to allocate a resource and manually manage its lifetime.

Parameters

  system | The system to create the resource into. If left to nullptr, then the Singleton instance will be used.

Returns
  The created resource instance.

The documentation for this class was generated from the following file:

- Documentation/Headers/NilkinsGraphics/Programs/Program.h